マルチバイト文字列をワイド文字列に変換する

mbstowcs_s関数は、マルチバイト文字セットの文字列をワイド文セットの文字列に変換します。

マルチバイト文字セット、ワイド文字セットについて、以下にまとめます。

マルチバイト文字セット	「ABC123」などの半角文字は1バイト、「あいうえお」などの全角文字は2バイトと、1文字あたりのバイト数の違う文字が混在した文字セット	Shift_JIS、EUC-JPなど
ワイド文字セット	すべての文字が2バイトで表現されている文字セット	Unicode(UCS-2、UTF-16など)

#include <stdlib.h>
errno_t mbstowcs_s( size_t *pReturnValue，

wchar_t *wcs，

size_t sizeInWords，

const char *mbs，

size_t count

);

pReturnValueは、変換された文字数です。[出力]

wcsは、ワイド文字セットの文字列(変換先)が格納される領域の先頭ポインタを指定します。[出力]

型wchar_tは、ワイド文字列を扱うための型で、C言語ではunsigned short型と同義です。

sizeInWordsは、wcsバッファのサイズ(文字数)です。[入力]

mbsは、マルチバイト文字セットの文字列(変換元)が格納された領域の先頭ポインタを指定します。[入力]

countは、wcsに格納するワイド文字の最大長(終端のnullは含まない)、または _TRUNCATEです。[入力]

_TRUNCATEを指定した場合、本関数は、終端文字1つ分を残して、変換先バッファに収まるだけの文字列まで変換を行います。

戻り値として、

正常終了した場合は0を、失敗した場合はエラーコードを返します。

以下はエラーコードと引数の対応です。

EINVAL	wcsがNULLでsizeInWords > 0 もしくは、mbsがNULL
ERANGE	wcsの指す領域サイズが小さいため、変換後の文字列が収まらない (countが_TRUNCATE の場合は、wcsの指す領域サイズに収まる範囲で処理されるため、失敗しません)

変換元の文字列の変換に成功すると、終端文字を含む変換した文字列のサイズ(ワイド文字単位)をpReturnValueに設定します(ただし、pReturnValueがNULLでない場合)。

※この動作は、wcsがNULLの場合でも実行されますので、これを使用して必要なバッファサイズを確認できます。

wcsがNULLの場合、countは無視されます。

また、無効なマルチバイト文字を検出すると、pReturnValueに0を、wcsに空の文字列を設定し、さらに、戻り値にEILSEQを返します。

なお、mbsとwcsの指す領域が重なる場合、本関数の動作は未定義(環境により動作が違う)です。

プログラム　例

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <locale.h>

int main(void)
{
  char *mbs = 'aあbいcう';
  wchar_t wcs[100];
  size_t ret;

  setlocale( LC_CTYPE， 'jpn' );

  mbstowcs_s(&ret， wcs， 100， mbs， _TRUNCATE);

  printf('マルチバイト文字列n');
  printf(' 文字列 = %sn'， mbs);
  printf(' バイト数 = %dn'， (int)strlen(mbs));
  printf('n');

  printf('ワイド文字列n');
  printf(' 文字列 = %wsn'， wcs);
  printf(' バイト数 = %dn'， wcslen(wcs) * sizeof(wchar_t));

  return 0;
}

例の実行結果

> mbstowcs_s.exe
マルチバイト文字列
 文字列 = aあbいcう
 バイト数 = 9

ワイド文字列
 文字列 = aあbいcう
 バイト数 = 12

※Windows環境でのみ動作確認しております。LINUX環境などでは動作が異なる場合がありますので、その場合は環境に合わせてカスタマイズしてください。

なお、本関数と同等の処理を行う関数に、mbstowcs()があります。

しかし、mbstowcs()はバッファオーバーフローを検知できないことがあるため、本関数の使用が推奨されています。